# 04 - Tool 系统

Tool 系统是 Claude Code 的核心——它定义了 Claude 与外部世界交互的所有能力。

---

## Tool 接口定义 (`src/Tool.ts`)

每个 Tool 都实现 `Tool<Input, Output, P>` 类型。以下是关键方法（按执行顺序排列）：

### 必需方法

| 方法 | 作用 |
|------|------|
| `name` | Tool 名称，如 `"Bash"`、`"Read"` |
| `inputSchema` | Zod schema 定义输入参数 |
| `validateInput()` | 输入校验，在权限检查之前 |
| `checkPermissions()` | 权限检查，返回 allow/deny/ask |
| `call()` | 实际执行逻辑 |
| `description()` | 动态生成 Tool 描述（给模型看） |
| `prompt()` | 生成 Tool 的使用说明 |
| `isReadOnly()` | 是否只读操作 |
| `isConcurrencySafe()` | 是否可安全并发执行 |
| `isEnabled()` | 是否启用 |

### 可选方法

| 方法 | 作用 |
|------|------|
| `aliases` | 别名，向后兼容 |
| `isDestructive()` | 是否不可逆操作（删除、覆盖、发送） |
| `interruptBehavior()` | 中断行为：`'cancel'` 或 `'block'` |
| `preparePermissionMatcher()` | 为 Hook 权限规则准备匹配器 |
| `getPath()` | 操作的文件路径 |
| `maxResultSizeChars` | 结果最大字符数，超出则持久化到磁盘 |
| `shouldDefer` | 是否延迟加载（需通过 ToolSearch 发现） |
| `renderToolUseMessage()` | UI 渲染：显示 Tool 调用 |
| `renderToolResultMessage()` | UI 渲染：显示 Tool 结果 |
| `backfillObservableInput()` | 给观察者添加衍生字段（不改原始输入） |

---

## 执行流程

```
模型发出 tool_use
      │
      ▼
1. validateInput(input, context)
   - 校验输入合法性
   - 失败 → 返回错误消息给模型
      │
      ▼
2. checkPermissions(input, context)
   - 返回: { result: 'allow' }
   -    或: { result: 'deny', message }
   -    或: { result: 'ask', ... }  → 弹出用户确认
      │
      ▼
3. call(input, context, canUseTool, parentMessage, onProgress?)
   - 实际执行操作
   - 返回: { data, newMessages?, contextModifier? }
```

---

## 返回值结构

```typescript
type ToolResult<T> = {
  data: T                    // 实际结果数据
  newMessages?: Message[]    // 可选：附加到对话的新消息
  contextModifier?: (ctx: ToolUseContext) => ToolUseContext  // 可选：修改上下文
  mcpMeta?: { ... }          // 可选：MCP 元数据透传
}
```

**重点**: `contextModifier` 只在**非并发安全**的 Tool 上生效。这是因为并发执行的 Tool 不能安全地修改共享上下文。

---

## 并发控制

```
Tool 调度决策
  │
  ├─ isConcurrencySafe() == true  → 并发执行（最多 10 个）
  │    例: FileRead, Glob, Grep（只读操作）
  │
  └─ isConcurrencySafe() == false → 串行执行
       例: Bash, FileEdit, FileWrite（写操作）
```

规则：
- **只读工具**并发安全，可同时执行多个
- **写入工具**串行执行，防止竞态条件
- 并发上限：10 个同时进行的 Tool

---

## ToolUseContext：执行上下文

每次 Tool 调用都接收一个 `ToolUseContext`，包含丰富的运行时信息：

```typescript
type ToolUseContext = {
  options: {
    commands: Command[]          // 可用命令
    tools: Tools                 // 可用工具
    mainLoopModel: string        // 当前模型
    mcpClients: MCPServerConnection[]  // MCP 连接
    thinkingConfig: ThinkingConfig     // 思考配置
    // ...
  }
  abortController: AbortController   // 中断控制
  readFileState: FileStateCache      // 文件状态缓存（防止 stale write）
  messages: Message[]                // 对话历史
  getAppState(): AppState            // 获取应用状态
  setAppState(f): void               // 更新应用状态
  // ...
}
```

---

## Tool 注册 (`src/tools.ts`)

所有 Tool 在 `getAllBaseTools()` 中注册：

```typescript
export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    FileReadTool,
    FileEditTool,
    FileWriteTool,
    NotebookEditTool,
    WebFetchTool,
    TodoWriteTool,
    WebSearchTool,
    AskUserQuestionTool,
    SkillTool,
    EnterPlanModeTool,
    ExitPlanModeV2Tool,
    // 条件性加载
    ...(isWorktreeModeEnabled() ? [EnterWorktreeTool, ExitWorktreeTool] : []),
    ...(isAgentSwarmsEnabled() ? [getTeamCreateTool(), getTeamDeleteTool()] : []),
    getSendMessageTool(),
    // Feature flag 控制
    ...(SleepTool ? [SleepTool] : []),
    ...cronTools,
    // ...更多
  ]
}
```

Tool 列表经过 `filterToolsByDenyRules()` 过滤后才提供给模型。被全局拒绝的 Tool 会从模型可见列表中完全移除。

---

## 完整 Tool 列表

### 文件操作
| Tool | 说明 |
|------|------|
| `BashTool` | 执行 Shell 命令（AST 解析、复合命令、后台执行） |
| `FileReadTool` | 读取文件（支持图片、PDF、Notebook、token 计数） |
| `FileEditTool` | 编辑文件（字符串替换，stale write 检测） |
| `FileWriteTool` | 创建/完全覆盖文件 |
| `GlobTool` | 文件模式搜索 |
| `GrepTool` | 内容搜索（基于 ripgrep） |
| `NotebookEditTool` | Jupyter Notebook 编辑 |

### Web 与搜索
| Tool | 说明 |
|------|------|
| `WebFetchTool` | 抓取 URL 内容 |
| `WebSearchTool` | 网页搜索 |

### Agent 与协作
| Tool | 说明 |
|------|------|
| `AgentTool` | 生成子 Agent |
| `SendMessageTool` | Agent 间发消息 |
| `TeamCreateTool` | 创建 Agent 团队 |
| `TeamDeleteTool` | 删除 Agent 团队 |

### 任务管理
| Tool | 说明 |
|------|------|
| `TodoWriteTool` | 待办列表（v1） |
| `TaskCreateTool` | 创建任务（v2） |
| `TaskGetTool` | 获取任务详情 |
| `TaskUpdateTool` | 更新任务状态 |
| `TaskListTool` | 列出所有任务 |
| `TaskOutputTool` | 读取后台任务输出 |
| `TaskStopTool` | 停止后台任务 |

### 规划与工作流
| Tool | 说明 |
|------|------|
| `EnterPlanModeTool` | 进入计划模式 |
| `ExitPlanModeV2Tool` | 退出计划模式 |
| `EnterWorktreeTool` | 进入 Git Worktree 隔离 |
| `ExitWorktreeTool` | 退出 Worktree |
| `SkillTool` | 执行技能 |

### 扩展协议
| Tool | 说明 |
|------|------|
| `MCPTool` | MCP 服务器工具调用 |
| `LSPTool` | 语言服务器协议调用 |
| `ListMcpResourcesTool` | 列出 MCP 资源 |
| `ReadMcpResourceTool` | 读取 MCP 资源 |

### 其他
| Tool | 说明 |
|------|------|
| `AskUserQuestionTool` | 向用户提问 |
| `ToolSearchTool` | 搜索延迟加载的 Tool |
| `BriefTool` | 简要模式输出 |
| `CronCreateTool` | 创建定时任务 |
| `RemoteTriggerTool` | 远程触发器 |
| `SleepTool` | 主动模式等待 |

### 条件加载 / Feature Flag 控制
| Tool | 说明 | 加载条件 |
|------|------|----------|
| `PowerShellTool` | Windows PowerShell 命令执行 | 平台为 Windows 时替代 BashTool |
| `VerifyPlanExecutionTool` | 验证计划执行结果 | Feature Flag `verify_plan_execution` |
| `SnipTool` | 代码片段捕获 | Feature Flag `snip_tool` |
| `ListPeersTool` | 列出对等 Agent | Feature Flag `list_peers` |
| `WorkflowTool` | 工作流编排执行 | Feature Flag `workflow_tool` |
| `MonitorTool` | 运行时监控与诊断 | Feature Flag `monitor_tool` |
| `CtxInspectTool` | 检查当前上下文内容 | Feature Flag `ctx_inspect` |
| `TerminalCaptureTool` | 捕获终端输出截图 | Feature Flag `terminal_capture` |
| `WebBrowserTool` | 浏览器自动化操作 | Feature Flag `web_browser` |

---

## 文件状态缓存 (FileStateCache)

防止 **stale write**（过时写入）的关键机制：

```
1. FileRead 读取文件 → 记录 (路径, 时间戳) 到 FileStateCache
2. FileEdit 编辑文件 → 检查 FileStateCache 中的时间戳
   - 匹配 → 安全执行编辑
   - 不匹配 → 文件已被外部修改，拒绝编辑
```

这避免了 Claude 基于过时内容做出编辑而覆盖用户的手动修改。